package jxerializeml.xml.transformers;

import jxerializeml.xml.FieldBean;
import jxerializeml.xml.NodeBean;

/**
 * <p>
 *   Used during deserialization.
 * </p>
 * <p>
 *   It transforms node beans to the (usually) field beans. Each
 *   document can be stored in many ways and this class should help
 *   with recognizing tag names and it's parameters.
 * </p>
 * 
 * @author Tomáš Zíma
 */
public interface InTransformer {
	/**
	 * This method will be called for each field.
	 * 
	 * @param nodeBean
	 *     All informations parsed from XML document
	 *     (tag name and all attributes).
	 *   
	 * @return
	 *     New instance of field bean, which will be
	 *     directly used for deserialization.
	 */
	FieldBean transformField(NodeBean nodeBean);
	
	/**
	 * This method will be called for each element of the array.
	 * 
	 * @param nodeBean
	 *     All informations parsed from XML document
	 *     (tag name and all attributes).
	 *   
	 * @return
	 *     New instance of field bean, which will be
	 *     directly used for deserialization.
	 */
	FieldBean transformArrayItem(NodeBean nodeBean);
	
	/**
	 * This method should be called only once, when root element
	 * of the document is parsed. From given informations, new
	 * instance of this (serialized) object will be created. After
	 * that, calls of the other methods will set up all it's fields.
	 * 
	 * @param nodeBean
	 *     All informations parsed from XML document
	 *     (tag name and all attributes).
	 *   
	 * @return
	 *     Name of the class of the serialized object. Using this,
	 *     new instance will be created.
	 *   
	 * @throws InvalidTransformerException
	 *     It was detected that the class was serialized with different
	 *     transformer than which was used for deserialization. It can
	 *     happen, for example, if attribute "transformer" contains
	 *     something different, or if it's even missing. It, however,
	 *     depends on each transformer. Some transformers may completely
	 *     ignore that and don't care about detecting transformer used for
	 *     the serialization.
	 */
	String transformRoot(NodeBean nodeBean) throws InvalidTransformerException;
	
	/**
	 * Tells to the parser meaning of some tag. Based on the result,
	 * appropriate method will be called.
	 * 
	 * @param nodeBean
	 *     All informations parsed from XML document
	 *     (tag name and all attributes).
	 *   
	 * @return
	 *     Type of the information.
	 *   
	 * @see
	 *     InformationType
	 */
	InformationType translate(NodeBean nodeBean);
}
